Black：严谨的 Python 代码格式化工具

在软件开发的世界里，一致性是关键。维护项目中的统一代码风格，尤其是在与全球分布式团队合作时，可以极大地提高可读性、减少错误并简化协作。在 Python 生态系统中，Black 是一款在强制执行统一风格方面表现突出的工具。

什么是 Black？

Black 是一款严谨的 Python 代码格式化工具。与其他提供大量配置选项的格式化工具不同，Black 故意限制了风格选择。这种“严谨”的方法意味着一旦您采用 Black，团队中的每个人——无论他们身在何处或背景如何——都将使用相同的、标准化的代码风格。这消除了关于格式化偏好的无休止的争论，让开发人员能够专注于解决实际问题。

Black 大体上遵循 PEP 8 风格指南，但在 PEP 8 存在歧义的地方，它也会做出自己的明智决定。这确保了高度的一致性，同时与普遍接受的 Python 最佳实践保持一致。

为什么使用 Black？全球性优势

使用 Black 的好处远远超出了美观。对于全球分布式团队而言，Black 提供了几个显著优势：

• 提高可读性： 统一的格式使代码更易于阅读和理解，无论谁编写的。这对于来自不同文化和语言背景的开发人员协作尤其重要。统一的风格就像一种通用语言，可以减少歧义和认知负荷。
• 减少代码审查时间： 通过自动将代码格式化为标准风格，Black 消除了许多可能困扰代码审查的挑剔性注释。审查人员可以专注于代码的逻辑和功能，而不是其格式。这导致更快速、更高效的代码审查流程。
• 简化协作： 当每个人都使用相同的格式化工具时，由于风格差异而导致的合并冲突会更少。这使得协作更加顺畅高效，尤其是在大型、地域分散的团队中。例如，一位在印度的开发人员可以无缝地为一位在德国的开发人员启动的项目做出贡献，而不会引入格式不一致。
• 新团队成员入职： Black 使新开发人员更容易加入项目。他们不必花时间学习项目的特殊风格指南；他们只需运行 Black，就可以确信他们的代码符合项目的标准。这加速了入职过程，并使新团队成员能够更快地投入生产。试想一下，一位在巴西的初级开发人员加入了一个由在美国和日本的资深开发人员组成的团队。Black 确保每个人都在相同的风格页面上。
• 降低认知负荷： 开发人员不再需要担心手动格式化他们的代码。Black 会自动处理，将他们的精力释放出来，让他们专注于更重要的任务。这在处理复杂项目或项目时间紧迫时尤其有价值。
• 强制执行最佳实践： 尽管“严谨”，Black 通过强制执行 PEP 8 指南并在 PEP 8 存在歧义的地方做出合理的格式化决定，来提倡良好的编码实践。这鼓励开发人员编写更清晰、更易于维护的代码。

开始使用 Black

使用 pip 安装 Black 非常简单：

            pip install black
            

              
                Copy
              
            
          

安装后，您可以通过运行以下命令格式化单个文件：

            black my_file.py
            

              
                Copy
              
            
          

要递归格式化整个目录：

            black my_directory
            

              
                Copy
              
            
          

Black 将自动原地重新格式化代码。如果您想在不实际修改文件的情况下查看 Black 将要进行的更改，可以使用 --diff 标志：

            black --diff my_file.py
            

              
                Copy
              
            
          

要检查文件是否已按照 Black 的风格进行格式化，您可以使用 --check 标志：

            black --check my_file.py
            

              
                Copy
              
            
          

这对于将 Black 集成到您的 CI/CD 管道（稍后将详细介绍）很有用。

将 Black 集成到您的工作流程

Black 可以通过多种方式无缝集成到您的开发工作流程中：

1. IDE 集成

许多流行的 IDE 和代码编辑器都提供 Black 的插件或扩展。这些集成允许您在保存文件时自动格式化代码。这是使用 Black 最方便的方式，因为它能确保您的代码始终格式正确。

以下是一些示例：

• VS Code： 安装 Microsoft 的“Python”扩展，并配置它使用 Black 作为格式化程序。在您的 settings.json 文件中添加以下内容：

              
   {
   "python.formatting.provider": "black",
   "editor.formatOnSave": true
   }
   
              
  
                
                  Copy
                
              
            

• PyCharm： 转到 Settings > Editor > Code Style > Python，并将方案设置为“Black”。您还可以在 Settings > Version Control > Commit 中启用“Reformat code after commit”。
• Sublime Text： 通过 Package Control 安装“Black”包。您可能需要配置 Black 可执行文件的路径。

2. Pre-commit 钩子

Pre-commit 钩子是在您将代码提交到版本控制系统之前自动运行的脚本。您可以使用 pre-commit 钩子运行 Black，并在每次提交前自动格式化代码。这可确保只有格式正确的代码才能提交到存储库。

要为 Black 设置 pre-commit 钩子，您可以使用 pre-commit 框架。首先，安装它：

            pip install pre-commit
            

              
                Copy
              
            
          

然后，在存储库的根目录中创建一个 .pre-commit-config.yaml 文件，内容如下：

            
 repos:
 - repo: https://github.com/psf/black
 rev: 24.3.0  # Replace with the latest version of Black
 hooks:
 - id: black
 
            

              
                Copy
              
            
          

运行 pre-commit install 来安装 pre-commit 钩子。现在，每次提交代码时，Black 都会自动运行。如果 Black 修改了任何文件，提交将被中止，您需要重新暂存更改并再次提交。

3. 持续集成 (CI/CD)

将 Black 集成到您的 CI/CD 管道可确保所有合并到主分支的代码都经过正确格式化。这可以通过在 CI/CD 管道中添加一个以检查模式运行 Black 的步骤来实现。如果 Black 检测到任何格式问题，管道将失败，从而阻止代码被合并。

例如，在 GitHub Actions 中，您可以将以下步骤添加到工作流程文件中：

            
 - name: Run Black
 uses: psf/black@v1
 with:
 options: "--check --verbose"
 src: "."
 
            

              
                Copy
              
            
          

这将以检查模式在存储库的所有文件上运行 Black。如果任何文件未正确格式化，操作将失败。

配置选项（有限）

如前所述，Black 故意限制了配置选项。但是，有几个选项可用：

• --line-length： 指定最大行长度。默认值为 88 个字符。虽然通常不鼓励，但增加此值可能对于使用长行的特定项目或遗留代码库是必要的。在偏离标准之前，请仔细考虑权衡。
• --target-version： 指定目标 Python 版本。如果您正在处理支持多个 Python 版本 Thus 项目，这将非常有用。Black 将调整其格式以与指定版本兼容。
• --include 和 --exclude： 指定用于包含或排除文件和目录进行格式化的正则表达式。这对于排除您不想格式化的生成代码或第三方库非常有用。例如，您可能在 Django 项目中排除一个 migrations 目录。

这些选项可以在命令行或存储库根目录的 pyproject.toml 文件中指定。例如：

            
 [tool.black]
 line-length = 120
 target-version = ['py37', 'py38', 'py39']
 exclude = 'migrations'
 
            

              
                Copy
              
            
          

解决常见顾虑和异议

虽然 Black 备受赞誉，但有些开发人员最初会抵制采用。以下是一些常见顾虑以及如何解决它们：

• “我不喜欢 Black 格式化我的代码的方式。” Black 有效性的关键在于其严谨性。抵制将其定制为个人偏好的冲动。拥抱标准化的风格，您很快就会发现一致性带来的好处远远超过任何个人审美偏好。请记住，目标是团队之间代码的一致性，而不是个人完美。
• “Black 会破坏我的代码。” Black 的设计宗旨是安全可靠的。但是，在用 Black 格式化代码后运行测试以确保一切正常总是个好主意。如果您确实遇到了 Black 的实际错误，请向开发者报告。
• “Black 太过于固执己见。” 这就是重点！Black 的固执己见使其在强制执行统一风格方面非常有效。它消除了关于格式化的无休止的争论，并允许开发人员专注于更重要的任务。
• “Black 使我的 diff 更难阅读。” 最初，大规模采用 Black 可能会产生大的 diff。鼓励开发人员一次格式化整个文件或模块，以最大程度地减少干扰，并在后续提交中专注于逻辑更改。初始格式化过程的短期不便是长期一致性带来的好处。

高级用法和技巧

• 逐步采用： 如果您有一个大型的现有代码库，一次性格式化整个代码库可能不切实际。考虑逐步采用 Black，从新代码或特定模块开始。您可以使用 --diff 和 --check 标志来识别需要格式化的文件。
• 与其他 Linter 结合使用： Black 仅专注于代码格式化。它不执行任何静态分析或代码 linting。考虑将 Black 与其他 linter（如 Flake8 或 Pylint）结合使用，以强制执行其他编码标准和最佳实践。例如，使用 Flake8 检查代码复杂性，使用 Black 进行格式化。
• 使用 # fmt: off 和 # fmt: on： 在极少数情况下，您可能需要为特定代码段禁用 Black。您可以使用 # fmt: off 和 # fmt: on 注释来实现。但是，请谨慎使用，因为它会破坏使用 Black 的目的。仅在 Black 严重影响可读性或可维护性的非常特殊的情况下使用。
• 考虑自定义 Black 插件（高级）： 虽然 Black 不鼓励广泛定制，但它允许创建插件。这些插件很少见，通常是为了解决非常具体的需求。仅在非常高级的场景中考虑此选项。

实际示例和案例研究

世界各地的许多组织都成功采用了 Black，包括：

• Instagram： 使用 Black 来维护其庞大的 Python 代码库的统一代码风格。
• Dropbox： 将 Black 作为其开发工作流程的一部分，以提高代码质量和协作。
• Mozilla： 将 Black 集成到其 CI/CD 管道中，以确保所有代码贡献都符合统一的风格。

这些组织，代表着不同的地理位置和组织结构，都认识到 Black 在提高代码质量、减少错误和简化协作方面的价值。

结论：拥抱一致性，拥抱 Black

Black 是在 Python 项目中强制执行统一代码风格的强大工具。它严谨的方法消除了风格争论，提高了可读性，并简化了协作，尤其是在全球分布式团队中。通过将 Black 集成到您的开发工作流程中，您可以专注于编写出色的代码，而不是担心格式。拥抱一致性，拥抱 Black，并释放您的 Python 开发团队的全部潜力，无论他们身在何处。

立即开始使用 Black，体验标准化代码风格带来的好处！